/* Copyright (c) 2025 Beijing Semidrive Technology Corporation
 * SPDX-License-Identifier: Apache-2.0
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
/** *****************************************************************************************************
 *  \file     Mcal_Cache.h                                                                              *
 *  \brief    This file contains interface header for MCALLIB Cache driver.                             *
 *                                                                                                      *
 * <table>                                                                                              *
 * <tr><th>Date           <th>Version                                                                   *
 * <tr><td>2024/07/02     <td>1.0.0                                                                     *
 * </table>                                                                                             *
 *******************************************************************************************************/
#ifndef MCAL_CACHE_H
#define MCAL_CACHE_H

#ifdef __cplusplus
extern "C" {
#endif
/**
 *
 * \defgroup MCAL McalLib Cache Driver
 *
 * The McalLib Cache Driver MCAL provides low level access to .<br>
 *
 * \sa MCAL_MCALLIB_CACHE_API
 *  \{
 */
/********************************************************************************************************
 *                                      Include header files                                            *
 *******************************************************************************************************/
#include "Mcal_Types.h"
/********************************************************************************************************
 *                                  Global Types definition                                             *
 *******************************************************************************************************/
/** \brief  cache type include instruction cache and data cache */
typedef enum
{
    MCAL_DCACHE = 0x01U,     /**< data cache */
    MCAL_ICACHE = 0x02U,     /**< instruction cache */
    MCAL_CACHE_ALL = 0x03U   /**< data and instruction cache */
}Mcal_CacheTypes;
/********************************************************************************************************
 *                                      Global fcuntion                                                 *
 *******************************************************************************************************/
/** *****************************************************************************************************
 * \brief This function provide a interface enable cache.
 *
 * \verbatim
 * Syntax             : Mcal_CacheEnable
 *
 * Service ID[hex]    : 0x00
 *
 * Sync/Async         : Synchronous
 *
 * Reentrancy         : Non reentrant
 *
 * Parameters (in)    : cacheType - cache type indicate i-cache or d-cache
 *
 * Parameters (inout) : None
 *
 * Parameters (out)   : None
 *
 * Return value       : None
 *
 * Description        : cache enable interface, user can select which cache type enabled include
 *                      i-cache/d-cache/i&d cache
 * \endverbatim
 * Traceability       : SWSR SWSR_LIB_003 SWSR_LIB_014
 *******************************************************************************************************/
void Mcal_CacheEnable(const Mcal_CacheTypes cacheType);
/** *****************************************************************************************************
 * \brief This function provide a interface disble cache.
 *
 * \verbatim
 * Syntax             : Mcal_CacheDisable
 *
 * Service ID[hex]    : 0x01
 *
 * Sync/Async         : Synchronous
 *
 * Reentrancy         : Non reentrant
 *
 * Parameters (in)    : cacheType - cache type indicate i-cache or d-cache
 *
 * Parameters (inout) : None
 *
 * Parameters (out)   : None
 *
 * Return value       : None
 *
 * Description        : cache disable interface, user can select which cache type disable include
 *                      i-cache/d-cache/i&d cache
 * \endverbatim
 * Traceability       : SWSR SWSR_LIB_004
 *******************************************************************************************************/
void Mcal_CacheDisable(const Mcal_CacheTypes cacheType);
/** *****************************************************************************************************
 * \brief This function service to flush cache.
 *
 * \verbatim
 * Syntax             : Std_ReturnType Mcal_FlushCache
 *                      (
 *                          uint32 Address
 *                          uint32 size
 *                      )
 *
 * Service ID[hex]    : 0x0B
 *
 * Sync/Async         : Synchronous
 *
 * Reentrancy         : Reentrant
 *
 * Parameters (in)    : address - Start address.
 *                      size    - Buffer size.
 *
 * Parameters (inout) : None
 *
 * Parameters (out)   : None
 *
 * Return value       : None
 *
 * Description        : This function service to clean and then invalidate cache memory.
 * \endverbatim
 * Traceability       : SWSR_MCALLIB_018 SWSR_MCALLIB_019 SWSR_MCALLIB_039 SWSR_MCALLIB_047 SWSR_MCALLIB_049 SW_SM006
 *******************************************************************************************************/
extern Std_ReturnType Mcal_FlushCache(uint32 address, uint32 size);
/** *****************************************************************************************************
 * \brief This function service to invalidae cache.
 *
 * \verbatim
 * Syntax             : Std_ReturnType Mcal_InvalidateCache
 *                      (
 *                          uint32 address
 *                          uint32 size
 *                      )
 *
 * Service ID[hex]    : 0x0C
 *
 * Sync/Async         : Synchronous
 *
 * Reentrancy         : Reentrant
 *
 * Parameters (in)    : address - Start address.
 *                      size    - Buffer size.
 *
 * Parameters (inout) : None
 *
 * Parameters (out)   : None
 *
 * Return value       : None
 *
 * Description        : This function service to read new data from RAM or ROM memory to cache.
 *
 * \endverbatim
 * Traceability       : SWSR_MCALLIB_018 SWSR_MCALLIB_019 SWSR_MCALLIB_039 SWSR_MCALLIB_047 SWSR_MCALLIB_049 SW_SM006
 *******************************************************************************************************/
extern Std_ReturnType Mcal_InvalidateCache(uint32 address, uint32 size);
/** *****************************************************************************************************
 * \brief This function service to clean cache.
 *
 * \verbatim
 * Syntax             : Std_ReturnType Mcal_CleanCache
 *                      (
 *                          uint32 address
 *                          uint32 size
 *                      )
 *
 * Service ID[hex]    : 0x0D
 *
 * Sync/Async         : Synchronous
 *
 * Reentrancy         : Reentrant
 *
 * Parameters (in)    : address - Start address.
 *                      size    - Buffer size.
 *
 * Parameters (inout) : None
 *
 * Parameters (out)   : None
 *
 * Return value       : None
 *
 * Description        : This function service to write cache memory data to RAM memor
 *
 * \endverbatim
 * Traceability       : SWSR_MCALLIB_018 SWSR_MCALLIB_019 SWSR_MCALLIB_039 SWSR_MCALLIB_047 SWSR_MCALLIB_049 SW_SM006
 *******************************************************************************************************/
extern Std_ReturnType Mcal_CleanCache(uint32 address, uint32 size);
#ifdef __cplusplus
}
#endif
#endif /* #ifndef DM_CACHE_H */
/* End of file */
